<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html><head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Standard File Control Opcodes</title>
<style type="text/css">
body {
    margin: auto;
    font-family: Verdana, sans-serif;
    padding: 8px 1%;
}

a { color: #044a64 }
a:visited { color: #734559 }

.logo { position:absolute; margin:3px; }
.tagline {
  float:right;
  text-align:right;
  font-style:italic;
  width:300px;
  margin:12px;
  margin-top:58px;
}

.toolbar {
  text-align: center;
  line-height: 1.6em;
  margin: 0;
  padding: 0px 8px;
}
.toolbar a { color: white; text-decoration: none; padding: 6px 12px; }
.toolbar a:visited { color: white; }
.toolbar a:hover { color: #044a64; background: white; }

.content    { margin: 5%; }
.content dt { font-weight:bold; }
.content dd { margin-bottom: 25px; margin-left:20%; }
.content ul { padding:0px; padding-left: 15px; margin:0px; }

/* rounded corners */
.se  { background: url(../images/se.gif) 100% 100% no-repeat #044a64}
.sw  { background: url(../images/sw.gif) 0% 100% no-repeat }
.ne  { background: url(../images/ne.gif) 100% 0% no-repeat }
.nw  { background: url(../images/nw.gif) 0% 0% no-repeat }

/* Things for "fancyformat" documents start here. */
.fancy img+p {font-style:italic}
.fancy .codeblock i { color: darkblue; }
.fancy h1,.fancy h2,.fancy h3,.fancy h4 {font-weight:normal;color:#044a64}
.fancy h2 { margin-left: 10px }
.fancy h3 { margin-left: 20px }
.fancy h4 { margin-left: 30px }
.fancy th {white-space:nowrap;text-align:left;border-bottom:solid 1px #444}
.fancy th, .fancy td {padding: 0.2em 1ex; vertical-align:top}
.fancy #toc a        { color: darkblue ; text-decoration: none }
.fancy .todo         { color: #AA3333 ; font-style : italic }
.fancy .todo:before  { content: 'TODO:' }
.fancy p.todo        { border: solid #AA3333 1px; padding: 1ex }
.fancy img { display:block; }
.fancy :link:hover, .fancy :visited:hover { background: wheat }
.fancy p,.fancy ul,.fancy ol { margin: 1em 5ex }
.fancy li p { margin: 1em 0 }
/* End of "fancyformat" specific rules. */

</style>
  
</head>
<body>
<div><!-- container div to satisfy validator -->

<a href="../index.html">
<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite Logo"
 border="0"></a>
<div><!-- IE hack to prevent disappearing logo--></div>
<div class="tagline">Small. Fast. Reliable.<br>Choose any three.</div>

<table width=100% style="clear:both"><tr><td>
  <div class="se"><div class="sw"><div class="ne"><div class="nw">
  <table width=100% style="padding:0;margin:0;cell-spacing:0"><tr>
  <td width=100%>
  <div class="toolbar">
    <a href="../about.html">About</a>
    <a href="../sitemap.html">Sitemap</a>
    <a href="../docs.html">Documentation</a>
    <a href="../download.html">Download</a>
    <a href="../copyright.html">License</a>
    <a href="../news.html">News</a>
    <a href="../support.html">Support</a>
  </div>
<script>
  gMsg = "Search SQLite Docs..."
  function entersearch() {
    var q = document.getElementById("q");
    if( q.value == gMsg ) { q.value = "" }
    q.style.color = "black"
    q.style.fontStyle = "normal"
  }
  function leavesearch() {
    var q = document.getElementById("q");
    if( q.value == "" ) { 
      q.value = gMsg
      q.style.color = "#044a64"
      q.style.fontStyle = "italic"
    }
  }
</script>
<td>
    <div style="padding:0 1em 0px 0;white-space:nowrap">
    <form name=f method="GET" action="http://www.sqlite.org/search">
      <input id=q name=q type=text
       onfocus="entersearch()" onblur="leavesearch()" style="width:24ex;padding:1px 1ex; border:solid white 1px; font-size:0.9em ; font-style:italic;color:#044a64;" value="Search SQLite Docs...">
      <input type=submit value="Go" style="border:solid white 1px;background-color:#044a64;color:white;font-size:0.9em;padding:0 1ex">
    </form>
    </div>
  </table>
</div></div></div></div>
</td></tr></table>
<div class=startsearch></div>
  
<a href="intro.html"><h2>SQLite C Interface</h2></a><h2>Standard File Control Opcodes</h2><blockquote><pre>#define SQLITE_FCNTL_LOCKSTATE               1
#define SQLITE_GET_LOCKPROXYFILE             2
#define SQLITE_SET_LOCKPROXYFILE             3
#define SQLITE_LAST_ERRNO                    4
#define SQLITE_FCNTL_SIZE_HINT               5
#define SQLITE_FCNTL_CHUNK_SIZE              6
#define SQLITE_FCNTL_FILE_POINTER            7
#define SQLITE_FCNTL_SYNC_OMITTED            8
#define SQLITE_FCNTL_WIN32_AV_RETRY          9
#define SQLITE_FCNTL_PERSIST_WAL            10
#define SQLITE_FCNTL_OVERWRITE              11
#define SQLITE_FCNTL_VFSNAME                12
#define SQLITE_FCNTL_POWERSAFE_OVERWRITE    13
#define SQLITE_FCNTL_PRAGMA                 14
</pre></blockquote><p>
These integer constants are opcodes for the xFileControl method
of the <a href="../c3ref/io_methods.html">sqlite3_io_methods</a> object and for the <a href="../c3ref/file_control.html">sqlite3_file_control()</a>
interface.</p>

<p>The <a href="../c3ref/c_fcntl_chunk_size.html">SQLITE_FCNTL_LOCKSTATE</a> opcode is used for debugging.  This
opcode causes the xFileControl method to write the current state of
the lock (one of <a href="../c3ref/c_lock_exclusive.html">SQLITE_LOCK_NONE</a>, <a href="../c3ref/c_lock_exclusive.html">SQLITE_LOCK_SHARED</a>,
<a href="../c3ref/c_lock_exclusive.html">SQLITE_LOCK_RESERVED</a>, <a href="../c3ref/c_lock_exclusive.html">SQLITE_LOCK_PENDING</a>, or <a href="../c3ref/c_lock_exclusive.html">SQLITE_LOCK_EXCLUSIVE</a>)
into an integer that the pArg argument points to. This capability
is used during testing and only needs to be supported when SQLITE_TEST
is defined.
<ul>
<li><a name="sqlitefcntlsizehint"></a>

The <a href="../c3ref/c_fcntl_chunk_size.html#sqlitefcntlsizehint">SQLITE_FCNTL_SIZE_HINT</a> opcode is used by SQLite to give the VFS
layer a hint of how large the database file will grow to be during the
current transaction.  This hint is not guaranteed to be accurate but it
is often close.  The underlying VFS might choose to preallocate database
file space based on this hint in order to help writes to the database
file run faster.</p>

<p><li><a name="sqlitefcntlchunksize"></a>

The <a href="../c3ref/c_fcntl_chunk_size.html#sqlitefcntlchunksize">SQLITE_FCNTL_CHUNK_SIZE</a> opcode is used to request that the VFS
extends and truncates the database file in chunks of a size specified
by the user. The fourth argument to <a href="../c3ref/file_control.html">sqlite3_file_control()</a> should
point to an integer (type int) containing the new chunk-size to use
for the nominated database. Allocating database file space in large
chunks (say 1MB at a time), may reduce file-system fragmentation and
improve performance on some systems.</p>

<p><li><a name="sqlitefcntlfilepointer"></a>

The <a href="../c3ref/c_fcntl_chunk_size.html#sqlitefcntlfilepointer">SQLITE_FCNTL_FILE_POINTER</a> opcode is used to obtain a pointer
to the <a href="../c3ref/file.html">sqlite3_file</a> object associated with a particular database
connection.  See the <a href="../c3ref/file_control.html">sqlite3_file_control()</a> documentation for
additional information.</p>

<p><li><a name="sqlitefcntlsyncomitted"></a>

The <a href="../c3ref/c_fcntl_chunk_size.html#sqlitefcntlsyncomitted">SQLITE_FCNTL_SYNC_OMITTED</a> opcode is generated internally by
SQLite and sent to all VFSes in place of a call to the xSync method
when the database connection has <a href="../pragma.html#pragma_synchronous">PRAGMA synchronous</a> set to OFF.
Some specialized VFSes need this signal in order to operate correctly
when <a href="../pragma.html#pragma_synchronous">PRAGMA synchronous=OFF</a> is set, but most
VFSes do not need this signal and should silently ignore this opcode.
Applications should not call <a href="../c3ref/file_control.html">sqlite3_file_control()</a> with this
opcode as doing so may disrupt the operation of the specialized VFSes
that do require it.</p>

<p><li><a name="sqlitefcntlwin32avretry"></a>

The <a href="../c3ref/c_fcntl_chunk_size.html#sqlitefcntlwin32avretry">SQLITE_FCNTL_WIN32_AV_RETRY</a> opcode is used to configure automatic
retry counts and intervals for certain disk I/O operations for the
windows <a href="../vfs.html">VFS</a> in order to provide robustness in the presence of
anti-virus programs.  By default, the windows VFS will retry file read,
file write, and file delete operations up to 10 times, with a delay
of 25 milliseconds before the first retry and with the delay increasing
by an additional 25 milliseconds with each subsequent retry.  This
opcode allows these two values (10 retries and 25 milliseconds of delay)
to be adjusted.  The values are changed for all database connections
within the same process.  The argument is a pointer to an array of two
integers where the first integer i the new retry count and the second
integer is the delay.  If either integer is negative, then the setting
is not changed but instead the prior value of that setting is written
into the array entry, allowing the current retry settings to be
interrogated.  The zDbName parameter is ignored.</p>

<p><li><a name="sqlitefcntlpersistwal"></a>

The <a href="../c3ref/c_fcntl_chunk_size.html#sqlitefcntlpersistwal">SQLITE_FCNTL_PERSIST_WAL</a> opcode is used to set or query the
persistent <a href="../wal.html">Write Ahead Log</a> setting.  By default, the auxiliary
write ahead log and shared memory files used for transaction control
are automatically deleted when the latest connection to the database
closes.  Setting persistent WAL mode causes those files to persist after
close.  Persisting the files is useful when other processes that do not
have write permission on the directory containing the database file want
to read the database file, as the WAL and shared memory files must exist
in order for the database to be readable.  The fourth parameter to
<a href="../c3ref/file_control.html">sqlite3_file_control()</a> for this opcode should be a pointer to an integer.
That integer is 0 to disable persistent WAL mode or 1 to enable persistent
WAL mode.  If the integer is -1, then it is overwritten with the current
WAL persistence setting.</p>

<p><li><a name="sqlitefcntlpowersafeoverwrite"></a>

The <a href="../c3ref/c_fcntl_chunk_size.html#sqlitefcntlpowersafeoverwrite">SQLITE_FCNTL_POWERSAFE_OVERWRITE</a> opcode is used to set or query the
persistent "powersafe-overwrite" or "PSOW" setting.  The PSOW setting
determines the <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_POWERSAFE_OVERWRITE</a> bit of the
xDeviceCharacteristics methods. The fourth parameter to
<a href="../c3ref/file_control.html">sqlite3_file_control()</a> for this opcode should be a pointer to an integer.
That integer is 0 to disable zero-damage mode or 1 to enable zero-damage
mode.  If the integer is -1, then it is overwritten with the current
zero-damage mode setting.</p>

<p><li><a name="sqlitefcntloverwrite"></a>

The <a href="../c3ref/c_fcntl_chunk_size.html#sqlitefcntloverwrite">SQLITE_FCNTL_OVERWRITE</a> opcode is invoked by SQLite after opening
a write transaction to indicate that, unless it is rolled back for some
reason, the entire database file will be overwritten by the current
transaction. This is used by VACUUM operations.</p>

<p><li><a name="sqlitefcntlvfsname"></a>

The <a href="../c3ref/c_fcntl_chunk_size.html#sqlitefcntlvfsname">SQLITE_FCNTL_VFSNAME</a> opcode can be used to obtain the names of
all <a href="../vfs.html">VFSes</a> in the VFS stack.  The names are of all VFS shims and the
final bottom-level VFS are written into memory obtained from
<a href="../c3ref/free.html">sqlite3_malloc()</a> and the result is stored in the char* variable
that the fourth parameter of <a href="../c3ref/file_control.html">sqlite3_file_control()</a> points to.
The caller is responsible for freeing the memory when done.  As with
all file-control actions, there is no guarantee that this will actually
do anything.  Callers should initialize the char* variable to a NULL
pointer in case this file-control is not implemented.  This file-control
is intended for diagnostic use only.</p>

<p><li><a name="sqlitefcntlpragma"></a>

Whenever a <a href="../pragma.html#syntax">PRAGMA</a> statement is parsed, an <a href="../c3ref/c_fcntl_chunk_size.html#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a>
file control is sent to the open <a href="../c3ref/file.html">sqlite3_file</a> object corresponding
to the database file to which the pragma statement refers. The argument
to the <a href="../c3ref/c_fcntl_chunk_size.html#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a> file control is an array of
pointers to strings (char**) in which the second element of the array
is the name of the pragma and the third element is the argument to the
pragma or NULL if the pragma has no argument.  The handler for an
<a href="../c3ref/c_fcntl_chunk_size.html#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a> file control can optionally make the first element
of the char** argument point to a string obtained from <a href="../c3ref/mprintf.html">sqlite3_mprintf()</a>
or the equivalent and that string will become the result of the pragma or
the error message if the pragma fails. If the
<a href="../c3ref/c_fcntl_chunk_size.html#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a> file control returns <a href="../c3ref/c_abort.html">SQLITE_NOTFOUND</a>, then normal
<a href="../pragma.html#syntax">PRAGMA</a> processing continues.  If the <a href="../c3ref/c_fcntl_chunk_size.html#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a>
file control returns <a href="../c3ref/c_abort.html">SQLITE_OK</a>, then the parser assumes that the
VFS has handled the PRAGMA itself and the parser generates a no-op
prepared statement.  If the <a href="../c3ref/c_fcntl_chunk_size.html#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a> file control returns
any result code other than <a href="../c3ref/c_abort.html">SQLITE_OK</a> or <a href="../c3ref/c_abort.html">SQLITE_NOTFOUND</a>, that means
that the VFS encountered an error while handling the <a href="../pragma.html#syntax">PRAGMA</a> and the
compilation of the PRAGMA fails with an error.  The <a href="../c3ref/c_fcntl_chunk_size.html#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a>
file control occurs at the beginning of pragma statement analysis and so
it is able to override built-in <a href="../pragma.html#syntax">PRAGMA</a> statements.
</ul>
</p><p>See also lists of
  <a href="objlist.html">Objects</a>,
  <a href="constlist.html">Constants</a>, and
  <a href="funclist.html">Functions</a>.</p>
